ParcelAddress API

(0 reviews)

Get Address Detail - dpid

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/{dpid}

Production:

https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/{dpid}

Resource Description

Returns the detailed information for a single dpid.

Resource Information

Attribute	Detail
Response Format	JSON
Requires Authentication	Yes
Rate Limited	15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Please note that all request parameters should be in lower case.

Request Parameters

Field Name	Description	Mand	Example
dpid	NZ Post address identifier	Yes	216250

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/dpid/12345

Response Parameters

The following lists the required fields in the Get Address Detail response message:

Field Name	Description	Mand	Example
Success	Returns if request is successful	Yes	True
Address	Address object with address details	Y if success = true	"address": {}

Address Object

The following lists the required fields in the address object.

Field Name	Description	Mand	Example
building_name	The name of the building	No	Sky Tower
company_name	The name of the company associated with the address (rarely available)	No	Acme Inventions
depot_name	The name of the depot that services this address	No	Akl City Fleet
floor	The floor number (if it exists)	No	3
latitude	The GPS latitude coordinate if the data exists	Yes	-45.9041
longitude	The GPS longitude coordinate if the data exists	Yes	170.552
postcode	The postcode associated with the address	Yes	2013
is_rural_delivery	Determines if this is a rural or a urban address (true for rural)	Yes	True
rural_delivery_number	The rural delivery number associated with the address	Yes If Rural Delivery = True	2
run_number	The run number that indicates which courier run will service this address	No	DCP003
gated_community_flag	Indication that address is within a gated community	No	True
street	The name of the street	Yes	Highbrook
street_alpha	The street address alphabetic code indicating multiple delivery locations at the street number eg 25a Main Street. The "a" is the alpha.	No	a
street_number	The street address number	Yes	22
street_type	Type of street	Yes	Avenue
suburb	The name of the suburb the address resides	Yes	Pakuranga
street suffix	Example is 151 victoria street west	Yes	West
city	The city the address resides in	Yes	Auckland
unit_type	The unit type of the address	No	Flat
unit_value	The unit value of the address	No	27
country	The name of the country the address resides	Yes	New Zealand
dpid	Delivery point identifier	No	54218

Error Response Elements

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	false
errors	Error object with error details	Y if success =false	See Error Object Parameters below
message_id	The unique message identifier	Yes	ec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field Name	Description	Example
code	Error code where first 3 digits are http status code, last three digits identify error type	400002
message	Description of error code	Invalid Parameter(s)
details	Description of specific error	No results returned. Check your Address ID and try again.

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

Code	Message
200	Success
400	Bad request
401	Unauthorized
403	Forbidden
409	Invalid request
500	System unavailable

Error Codes

Code	Message
200001	Partial results returned, not all system(s) have responded
200002	All sources responded, data may be incomplete
400001	Parameter(s) missing
400002	Invalid parameter(s)
400003	Non mutually exclusive parameters detected
401001	Unauthorised access, please contact administrator
500001	General Exception
500002	System(s) offline

Sample Response

Sample success response:

{

   "success": true,

   "address":    {

      "street_number": 71,

      "street": "Oregon",

      "street_type": "Street",

      "suburb": "Ocean Grove",

      "city": "Dunedin",

      "is_rural_delivery": false,

      "postcode": "9013",

      "longitude": 170.552,

      "latitude": -45.9041,

      "run_number": "DCP025  ",

      "depot_name": "Dunedin Depot",

      "country": "New Zealand",

      "dpid": "54218",

   },

   "message_id": "618a5799-85e3-4559-8a62-280f231a26b3"

}

Sample failure response:

{

   "success": true,

   "errors": [   {

      "code": "400002",

      "message": "Invalid parameter(s)",

      "details": "No results returned. Check your Address ID and try again. "

   }],

   "message_id": "e5d56f1c-d6f7-4742-a7f8-c411fdb6cae5"

}